card-validator

What is card-validator?

The card-validator npm package is a library for validating credit card information. It provides utilities to validate card numbers, expiration dates, and CVV codes, among other features. This package is useful for developers who need to ensure that the credit card information entered by users is valid before processing payments.

What are card-validator's main functionalities?

Validate Card Number

This feature allows you to validate a credit card number. The code sample demonstrates how to use the `number` method to check if a given card number is valid.

const cardValidator = require('card-validator');
const numberValidation = cardValidator.number('4111111111111111');
console.log(numberValidation.isValid); // true

Validate Expiration Date

This feature allows you to validate the expiration date of a credit card. The code sample shows how to use the `expirationDate` method to check if a given expiration date is valid.

const cardValidator = require('card-validator');
const expirationDateValidation = cardValidator.expirationDate('12/23');
console.log(expirationDateValidation.isValid); // true

Validate CVV

This feature allows you to validate the CVV code of a credit card. The code sample demonstrates how to use the `cvv` method to check if a given CVV code is valid.

const cardValidator = require('card-validator');
const cvvValidation = cardValidator.cvv('123');
console.log(cvvValidation.isValid); // true

Other packages similar to card-validator

creditcard.js

creditcard.js is a library for validating credit card numbers, expiration dates, and CVV codes. It offers similar functionalities to card-validator but with a different API design. It is also lightweight and easy to integrate into web applications.

card

The card package provides utilities for validating and formatting credit card information. It includes features for validating card numbers, expiration dates, and CVV codes, similar to card-validator. Additionally, it offers formatting utilities to display card information in a user-friendly manner.

payment

The payment package is a comprehensive library for handling credit card validation and formatting. It includes features for validating card numbers, expiration dates, and CVV codes, as well as utilities for formatting and masking card information. It is a robust alternative to card-validator with additional formatting capabilities.

README

Credit Card Validator

Credit Card Validator provides validation utilities for credit card data inputs. It is designed as a CommonJS module for use in Node.js, io.js, or the browser. It includes first class support for 'potential' validity so you can use it to present appropriate UI to your user as they type.

A typical use case in a credit card form is to notify the user if the data they are entering is invalid. In a credit card field, entering “411” is not necessarily valid for submission, but it is still potentially valid. Conversely, if a user enters “41x” that value can no longer pass strict validation and you can provide a response immediately.

Credit Card Validator will also provide a determined card type (using credit-card-type). This is useful for scenarios in which you wish to render an accompanying payment method icon (Visa, MasterCard, etc.). Additionally, by having access to the current card type, you can better manage the state of your credit card form as a whole. For example, if you detect a user is entering (or has entered) an American Express card number, you can update the maxlength attribute of your CVV input element from 3 to 4 and even update the corresponding label from 'CVV' to 'CID'.

Download

You can install card-validator through npm.

npm install card-validator

Example

Using a CommonJS build tool (browserify, webpack, etc)

var valid = require('card-validator');

var numberValidation = valid.number('4111');

if (!numberValidation.isPotentiallyValid) {
  renderInvalidCardNumber();
}

if (numberValidation.card) {
  console.log(numberValidation.card.type); // 'visa'
}

API

var valid = require('card-validator');

---

valid.number(value: string, [options: object]): object

{
  card: {
    niceType: 'American Express',
    type: 'american-express',
    gaps: [4, 10],
    lengths: [15],
    code: {name: 'CID', size: 4}
  },
  isPotentiallyValid: true, // if false, indicates there is no way the card could be valid
  isValid: true // if true, number is valid for submission
}

You can optionally pass luhnValidateUnionPay as a property of an object as a second argument. This will override the default behavior to ignore luhn validity of UnionPay cards.

valid.number(<Luhn Invalid UnionPay Card Number>, {luhnValidateUnionPay: true});

{
  card: {
    niceType: 'UnionPay',
    type: 'unionpay',
    gaps: [4, 8, 12],
    lengths: [16, 17, 18, 19],
    code: {name: 'CVN', size: 3}
  },
  isPotentiallyValid: true,
  isValid: false // Would be true if no options were included
}

You can optionally pass maxLength as a property of an object as a second argument. This will override the default behavior to use the card type's max length property and mark any cards that exceed the max length as invalid.

If a card brand has a normal max length that is shorter than the passed in max length, the validator will use the shorter one. For instance, if a maxLength of 16 is provided, the validator will still use 15 as the max length for American Express cards.

valid.number(<Maestro Card with 19 Digits>, {maxLength: 16});

{
  card: {
    // Maestro card data
  },
  isPotentiallyValid: false,
  isValid: false
}

If a valid card type cannot be determined, the card field in the response will be null.

A fake session where a user is entering a card number may look like:

Input	Output	Suggested Handling
Value	card.type	isPotentiallyValid	isValid	Render Invalid UI	Allow Submit
''	null	true	false	no	no
'6'	null	true	false	no	no
'60'	'discover'	true	false	no	no
'601'	'discover'	true	false	no	no
'6011'	'discover'	true	false	no	no
'601'	'discover'	true	false	no	no
'60'	'discover'	true	false	no	no
'6'	null	true	false	no	no
''	null	true	false	no	no
'x'	null	false	false	yes	no
''	null	true	false	no	no
'4'	'visa'	true	false	no	no
'41'	'visa'	true	false	no	no
'411'	'visa'	true	false	no	no
'4111111111111111'	'visa'	true	true	no	yes
'411x'	null	false	false	yes	no

---

valid.expirationDate(value: string|object, maxElapsedYear: integer): object

The maxElapsedYear has a default value of 19. It can be overridden by passing in an integer as a second argument.

{
  isPotentiallyValid: true, // if false, indicates there is no way this could be valid in the future
  isValid: true,
  month: '10', // a string with the parsed month if valid, null if either month or year are invalid
  year: '2016' // a string with the parsed year if valid, null if either month or year are invalid
}

expirationDate will parse strings in a variety of formats:

Input	Output
'10/19' '10 / 19' '1019' '10 19'	{month: '10', year: '19'}
'10/2019' '10 / 2019' '102019' '10 2019' '10 19'	{month: '10', year: '2019'}
'2019-10'	{month: '10', year: '2019'}
{month: '01', year: '19'} {month: '1', year: '19'} {month: 1, year: 19}	{month: '01', year: '19'}
{month: '10', year: '2019'} {month: '1', year: '2019'} {month: 1, year: 19}	{month: '10', year: '2019'}

---

valid.expirationMonth(value: string): object

expirationMonth accepts 1 or 2 digit months. 1, 01, 10 are all valid entries.

{
  isValidForThisYear: false,
  isPotentiallyValid: true,
  isValid: true
}

---

valid.expirationYear(value: string, maxElapsedYear: integer): object

expirationYear accepts 2 or 4 digit years. 16 and 2016 are both valid entries.

The maxElapsedYear has a default value of 19. It can be overridden by passing in an integer as a second argument.

{
  isCurrentYear: false,
  isPotentiallyValid: true,
  isValid: true
}

---

valid.cvv(value: string, maxLength: integer): object

The cvv validation by default tests for a numeric string of 3 characters in length. The maxLength can be overridden by passing in an integer as a second argument. You would typically switch this length from 3 to 4 in the case of an American Express card which expects a 4 digit CID.

{
  isPotentiallyValid: true,
  isValid: true
}

---

valid.postalCode(value: string, [options: object]): object

The postalCode validation essentially tests for a valid string greater than 3 characters in length.

{
  isPotentiallyValid: true,
  isValid: true
}

You can optionally pass minLength as a property of an object as a second argument. This will override the default min length of 3.

valid.postalCode('123', {minLength: 5});

{
  isPotentiallyValid: true,
  isValid: false
}

Custom Card Brands

Card Validator exposes the credit-card-type module as creditCardType. You can add custom card brands by utilizing the addCard method.

valid.creditCardType.addCard({
  niceType: 'NewCard',
  type: 'new-card',
  patterns: [
    1234
  ],
  gaps: [4, 8, 12],
  lengths: [16],
  code: {
    name: 'CVV',
    size: 3
  }
});

Design decisions

• The default maximum expiration year is 19 years from now.
• valid.expirationDate will only return month: and year: as strings if the two are valid, otherwise they will be null.
• Since non-US postal codes are alpha-numeric, the postalCode will allow non-number characters to be used in validation.

Development

We use nvm for managing our node versions, but you do not have to. Replace any nvm references with the tool of your choice below.

nvm install
npm install

All testing dependencies will be installed upon npm install. Run the test suite with npm test.

Changelog

6.2.0

• Adjust expiration date to accept dates formatted as YYYY-MM (the HTML autofill spec). Closes #69 (thanks @schuylr)

  6.1.0

• Add option to set a maxLength for card number validation

  6.0.0

• Update credit-card-type to v8.0.0

Breaking Changes

• When adding or updating cards, this module no longer uses an exactPattern and prefixPattern model. Instead, it takes an array of patterns. See https://github.com/braintree/credit-card-type#pattern-detection for details.

  5.1.0

• Add optional options object with luhnValidateUnionPay parameter to force luhn validity check of UnionPay cards

• Update tests to account for ELO cards

  5.0.0

• Update credit-card-type to v7.0.0

Breaking Changes

• Mastercard enum changed from master-card to mastercard

  4.3.0

• Support custom card brands

• Require minimum version of credit-card-type to be v6.2.0

  4.2.0

• Allow maxElapsedYear to be configurable in expirationYear and expirationDate (thanks @wozaki)

  4.1.1

• Update credit-card-type to v6.0.0

  4.1.0

• Add options object for postal code validation to specify min length

  4.0.0

• Breaking change: Remove dist files. You must use npm to use this module

• Breaking change: Remove support for primitive constructors like new String()

  3.0.1

• Fix postal code validation to be valid if 3 or more characters

  3.0.0

• correctly identify Maestro cards beginning with 6

• Breaking change: The format of the card object returned has changed. pattern has been replaced by prefixPattern and exactPattern.

  2.3.0

• valid.expirationDate can take an object with month and year fields or a string value

  2.2.8

• Update dist to include version 4.0.3 of credit-card-type

  2.2.7

• Including dist from 2.2.6

  2.2.6

• Fixes cases where card numbers were incorrectly reported as isPotentiallyValid: false when more digits could still be entered

  • issue #20 and PR #21

  2.2.5

• Fixes expiration date results when year is current year and month is invalid

• Update files in dist/

• Readme clarifications

  2.2.4

• Fixes validation of space separated expiration dates

• Fixes potential validity of slashless expiration dates

• Fixes validation of expiration dates that are too long

  2.2.3

• Fixes CVV validation to not always validate 3-digit values as isValid: true

  2.2.2

• Fixes 3-digit expiration date handling, such as 220 being Feb, 2020

  2.2.1

• Use one Lodash dependency

  2.2.0

• CVV validator can accept an array of possible length values

  2.1.0

• Contextually validate month based on current date.

  2.0.2

• Update credit-card-type to 4.0.0

  2.0.1

• The npm module now includes built files under dist/.

  2.0.0

• The returned value for card.length is now an Array and called card.lengths to account for variable-length cards such as UnionPay.

  1.0.0

• Initial release